<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>MRtrix documentation</title>
<link rel="stylesheet" href="../stylesheet.css" type="text/css" media=screen>
</head>
<body>

<table class=nav>
  <tr>
    <td><a href="cmdline.html"><img src="../left.png"></a></td>
    <td><a href="index.html"><img src="../up.png"></a></td>
    <td><a href="../index.html"><img src="../home.png"></a></td>
    <th>Image File Formats</th>
    <td><a href="mrview.html"><img src="../right.png"></a></td>
  </tr>
</table>


<h2><a name='formats'>Supported image file formats</a></h2>
<p>
This is a list of currently supported file formats. Note that some of these formats may be supported only for reading or writing.
</p>
<ul>
<li><a href='#DICOM'>DICOM</a></li>
<li><a href='#NIfTI'>NIfTI 1.1 (*.nii)</a></li>
<li><a href='#AVW'>Analyse/SPM (*.hdr/*.img)</a></li>
<li><a href='#MRtrix'>MRtrix (*.mif or *.mih)</a></li>
<li><a href='#XDS'>XDS (*.hdr/*.bfloat or *.hdr/*.bshort)</a></li>
<!-- <li><a href='#Siemens'>Siemens Vision (*.ima)</a></li>
<li><a href='#InterFile'>InterFile (*.HDR/*.IMG)</a></li> -->
<li><a href='#MRTools_old'>Legacy MRTools (*.mri)</a></li>
</ul>

<p>
MRtrix determines the image format from the identifier specified on the command-line (typically its suffix). 
Certain image formats use multiple files per data set (e.g. the Analyse <kbd>*.hdr/*.img</kbd> pair). 
For this reason, the image identifier may not correspond to a real file. 
Its function is to supply the program with enough information to infer which files are to be read or created. 
For example, the image identifier <kbd>/data/image-[1:5].img</kbd> instructs MRtrix applications 
to access a data set consisting of five Analyse format images, stored in the <kbd>/data</kbd> folder, 
with filenames <kbd>image-1.img</kbd> to <kbd>image-5.img</kbd>.
</p>
<p>
MRtrix applications are all inherently capable of accessing binary data stored in any common format
(i.e. precision, byte order, etc); these data types are listed <a href="#datatypes">here</a>.
However, not all image formats support such a wide range of data types.
With a few exceptions, most MRtrix programs will request the same data type for the output images as for the input images. 
The program will then attempt to use the requested data type if the image format can support it,
or will otherwise substitute a hopefully appropriate replacement.

<h3><a name="multi">Combining multiple images into a single data set</a></h3>
<p>
For most image file formats, it is possible to combine multiple images into a single higher-dimensional data set
on the command-line by using <a href="cmdline.html#sequences">number sequences</a>.
If the filename contains a number sequence between square brackets, 
the application will attempt to match the numbers specified (if any) with any existing files (when reading) 
or will generate files with the numbers specified (when writing). 
For example:
</p>
<pre>
&gt; <b><a href='../commands/mrconvert.html'>mrconvert</a> in-[20:40].mif out-[].img</b>
<a href='../commands/mrconvert.html'>mrconvert</a>: copying data... 100%
</pre>
<p>
will convert the MRtrix format images <kbd>in-20.mif</kbd> through to <kbd>in-40.mif</kbd> (interpreted as a single data set)
into the set of Analyse images <kbd>out-00.img</kbd> through to <kbd>in-20.img</kbd>.
</p>
<p>
This syntax will fail if any of the image files that match the specifier have different dimensions or data types,
since it then becomes impossible to combine the images into a single coherent data set.
</p>



<p class=sep><a href="#top">top</a></p>

<h3><a name='DICOM'>DICOM</a></h3>
<p>
DICOM format is only supported for reading. MRtrix applications will assume an image is in DICOM format if 
the image specifier provided corresponds to a folder. The application will scan the entire folder and its subfolders
for DICOM files and generate a list of DICOM patients, studies and series. If a single series is found within the
folder, this data set will be accessed with no further interaction required. Otherwise, the user will be prompted 
to select the series of interest. Images stored as mosaics should be correctly interpreted (at least on Siemens VB13 and above).
</p>
<p>
For example, assuming the folder <kbd>/data/DICOM_folder/</kbd> contains a set of DICOM images, 
the following command will print its corresponding header information:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> /data/DICOM_folder/</b>
<a href='../commands/mrinfo.html'>mrinfo</a>: scanning DICOM folder "/data/DICOM_folder/"  - ok
<a href='../commands/mrinfo.html'>mrinfo</a>: reading DICOM series "t1_mpr_0.9 iso hres"... 100%
************************************************
Image:               "VOLUNTEER(000366) [MR] t1_mpr_0.9 iso hres"
************************************************
  Format:            DICOM
  Dimensions:        192 x 256 x 256
  Voxel size:        0.9 x 0.898438 x 0.898438
  Dimension labels:  0. inferior->superior (mm)
                     1. left->right (mm)
                     2. posterior->anterior (mm)
  Data type:         unsigned 16 bit integer (little endian)
  Data layout:       [ +2 -0 -1 ]
  Data scaling:      offset = 0, multiplier = 1
  Comments:          VOLUNTEER(000366) [MR] t1_mpr_0.9 iso hres
  Transform:              0.998  -0.05412  -0.03311    -74.03
                        0.05409    0.9985 -0.001794    -100.6
                        0.03316  2.34e-08    0.9995    -125.8
                              0         0         0         1
</pre>
<p>
A separate application, <kbd><a href='../commands/read_dicom.html'>read_dicom</a></kbd>, 
is provided to view all DICOM header elements within a particular DICOM file. 
</p>
<p>
Note that no support is provided for reading the <kbd>DICOMDIR</kbd> entry due to case-sensitivity issues.
DICOM data are typically stored on CD or DVD on a case-insensitive filesystem. 
However, Unix systems will typically not access these filesystems in a case-insensitive manner,
and will fail to find the appropriate files if the case of filenames supplied in the DICOMDIR file does not 
match the case of the files found on the CD or DVD.
</p>



<p class=sep><a href="#top">top</a></p>

<h3><a name='NIfTI'>NIfTI 1.1 (*.nii)</a></h3>
<p>
This file format is supported both for reading and writing, and allows interoperation with other packages 
such as <a href='http://www.fil.ion.ucl.ac.uk/spm/'>SPM5</a> or <a href='http://www.fmrib.ox.ac.uk/fsl/'>FSL</a>. 
In order to specify a NIfTI format image on the command line, simply specify the name of the file.
For example:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> example.nii</b>
</pre>
<p>
<strong>Notes:</strong>
</p>
<ul>
  <li>the hdr/img version of the NIfTI format is only supported for reading (see <a href='#AVW'>Analyse</a> format).</li>
  <li>MRtrix is currently only capable of handling uncompressed single-file NIfTI images (with the <kbd>*.nii</kbd>) suffix).<br>
  If needed, you can use the <kbd>gunzip</kbd> command to decompress your images for use with MRtrix. For example:<br>
  <pre>&gt; <b>gunzip example.nii.gz</b></pre></li>
  <li>if both qform and sform orientation fields are present, the qform fields are ignored. 
  Obviously, the qform fields will be used if they are present on their own.</li>
</ul>

<p class=sep><a href="#top">top</a></p>

<h3><a name='AVW'>Analyse/SPM format (*.hdr/*.img)</a></h3>
<p>
This file format is supported both for reading and writing. 
In order to specify an Analyse format image on the command line, type the name of its data file (<kbd>*.img</kbd>).
For example:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> example.img</b>
</pre>
<p>
will display the image header information found in the file <kbd>example.hdr</kbd> that corresponds to the data file <kbd>example.img</kbd>.
</p>
<p>
<strong>Notes:</strong>
</p>
<ul>
  <li> by default, image data in Analyse format files are stored in neurological convention (i.e. left to right, the SPM99 convention). 
  If required, this can be changed by adding the line:<br><pre>Analyse.LeftToRight: false</pre> 
  in the MRtrix config file (<kbd>/etc/mrtrix.conf</kbd> or <kbd>~/.mrtrix.conf</kbd> on Unix, 
  <kbd>C:\mrtrix.conf</kbd> or <kbd>$HOMEDIR\mrtrix.conf</kbd> on Windows).</li>
</p>
  <li>Analyse format images cannot be specified using their header file (<kbd>*.hdr</kbd>) 
  to avoid ambiguities with the XDS format, which also makes use of a header file with the same suffix.</li>
  <li>NIfTI 1.1 images stored as hdr/img will be read correctly (in particular, any orientation information will be parsed correctly).
  However, for simplicity and compatibility any hdr/img pairs produced by MRtrix will be in the standard Analyse format, rather than NIfTI 1.1.</li>
</ul>



<p class=sep><a href="#top">top</a></p>

<h3><a name='MRtrix'>MRtrix (*.mif or *.mih)</a></h3>
<p>
This is the standard image file format for MRtrix. It is supported both for reading and writing.
To use it, simply type the name of the <kbd>*.mif</kbd> or <kbd>*.mih</kbd> file where appropriate in the command, for example:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> example.mif</b>
</pre>
<p>
There are two versions of this format: 
</p>
<dl>
  <dt>MRtrix Image Header (<kbd>*.mih</kbd>)</dt>
  <dd>This constists of a header/data file pair. The header is a simple text file with the suffix <kbd>*.mih</kbd>, 
  with the name of the data file given in the header itself. 
  The text header consists of a set of key/value entries, one per line, and is described in more detail <a href="../appendix/mrtrix.html">here</a>.
  This format is useful for importing or exporting data to or from other applications, since the header can easily be read or written using a simple text editor.</dd>
  <dt>MRtrix Image File (<kbd>*.mif</kbd>)</dt>
  <dd>This constists of a single file with suffix <kbd>*.mif</kbd>, which is essentially the concatenation of the text header, followed by the binary image data.</dd>
</dl>

<p>
The MRtrix image format supports all the data types listed <a href="#datatypes">below</a>, all <a href="#dataorder">data ordering schemes</a>, 
and any number of dimensions. In addition, the header is capable of storing any relevant information. 
It is therefore the preferred image format to use with MRtrix applications.
</p>



<p class=sep><a href="#top">top</a></p>

<h3><a name='XDS'>XDS (*.hdr/*.bfloat or *.hdr/*.bshort)</a></h3>
<p>
This is the format used by the XDS package, and is supported both for reading and writing. 
Note that the XDS header only contains the data set dimensions; 
all other header information (in particular voxel size) that may have been contained in the image header will be lost 
when converting to this format. 
</p>
<p>
In this format, image files contain a single-slice time series;
<a href="#multi">multiple files will need to be combined</a> in order to access a full volume data set.
The XDS format is assumed if the image specifier ends in <kbd>*.bfloat</kbd> (<a href="#datatypes">Float32 data type</a>)
or in <kbd>*.bshort</kbd> (<a href="#datatypes">UInt16 data type</a>).
Here is a typical example:
</p>
<pre>
&gt; <b><a href='../commands/mrconvert.html'>mrconvert</a> original-[3,4,5].bshort converted-[].bfloat</b>
</pre>



<p class=sep><a href="#top">top</a></p>

<h3><a name='MRTools_old'>Legacy MRTools (*.mri)</a></h3>
<p>
This is the legacy image file format for MRtrix, and is now deprecated. 
It consists of a single file, and supports 4-dimensional data.
It is currently only supported for reading.
</p>
<p>
To use it, simply type the name of the file where appropriate in the command, for example:
</p>
<pre>
&gt; <b><a href='../commands/mrinfo.html'>mrinfo</a> example.mri</b>
</pre>







<p class=sep><a href="#top">top</a></p>

<h2><a name='datatypes'>Supported data types</a></h2>
<p>
All MRtrix applications can read or write images using any of the data types listed below. 
Converting an existing image into one using any desired data type can be achieved 
by supplying the <kbd>-datatype</kbd> option to <kbd><a href='../commands/mrconvert.html'>mrconvert</a></kbd>.
</p>
<p>
Any data type larger than 8 bits (i.e. one byte) can be stored according to different byte-ordering conventions.
By far the most common such conventions are <em>little-endian</em> (found on Intel x86 platforms, including the new generation of Macs) 
and <em>big-endian</em> (found on older Macs and SUN Sparc platforms, amongst others).
The desired byte order for these data types can be specified by appending the suffix <kbd>LE</kbd> or <kbd>BE</kbd> to the data type specifier.
If unspecified, native byte ordering will be assumed.
</p>

<table width=100%>
<tr><th width=30%>Specifier</th><th>Description</th></tr>
<tr><td>Bit</td><td>bitwise data</td></tr>
<tr><td>Int8</td><td>signed 8-bit (char) integer</td></tr>
<tr><td>UInt8</td><td>unsigned 8-bit (char) integer</td></tr>
<tr><td>Int16</td><td>signed 16-bit (short) integer</td></tr>
<tr><td>UInt16</td><td>unsigned 16-bit (short) integer</td></tr>
<tr><td>Int16LE</td><td>signed 16-bit (short) integer (little-endian)</td></tr>
<tr><td>UInt16LE</td><td>unsigned 16-bit (short) integer (little-endian)</td></tr>
<tr><td>Int16BE</td><td>signed 16-bit (short) integer (big-endian)</td></tr>
<tr><td>UInt16BE</td><td>unsigned 16-bit (short) integer (big-endian)</td></tr>
<tr><td>Int32</td><td>signed 32-bit int</td></tr>
<tr><td>UInt32</td><td>unsigned 32-bit int</td></tr>
<tr><td>Int32LE</td><td>signed 32-bit int (little-endian)</td></tr>
<tr><td>UInt32LE</td><td>unsigned 32-bit int (little-endian)</td></tr>
<tr><td>Int32BE</td><td>signed 32-bit int (big-endian)</td></tr>
<tr><td>UInt32BE</td><td>unsigned 32-bit int (big-endian)</td></tr>
<tr><td>Float32</td><td>32-bit floating-point</td></tr>
<tr><td>Float32LE</td><td>32-bit floating-point (little-endian)</td></tr>
<tr><td>Float32BE</td><td>32-bit floating-point (big-endian)</td></tr>
<tr><td>Float64</td><td>64-bit (double) floating-point</td></tr>
<tr><td>Float64LE</td><td>64-bit (double) floating-point (little-endian)</td></tr>
<tr><td>Float64BE</td><td>64-bit (double) floating-point (big-endian)</td></tr>
</table>



<p class=sep><a href="#top">top</a></p>

<h2><a name='dataorder'>Data Ordering</a></h2>
<p>
Data can be stored in the image files in different orders. 
For example, a particular image format might specify that the bottom left posterior corner voxel is stored first in the file, 
and that subsequent values in the file correspond to voxels immediately to the right of the previous one. 
Other image formats might specify that the top right corner voxel is stored first.
MRtrix applications are capable of handling all (reasonable) such data ordering schemes,
as long as the image format has fully specified how the file is to be interpreted. 
</p>
<p>
With MRtrix, data ordering is specified using a comma-separated list of axis specifiers, 
each of which consists of a plus or minus sign to indicate polarity, followed by the axis number.
For example, the specifier <kbd>-0,-1,+2,+3</kbd> indicates that data values are stored right to left first, 
then anterior to posterior, then inferior to superior and finally in increasing order along the 4th dimension 
(which might for example correspond to the time dimension). 
This type of ordering might be used for a standard DICOM axial time-series.
</p>
The interpretation of the ordering specifier is often not trivial. 
The illustration below should help to clarify its proper meaning.
</p>
<img src='data_order.png'>
<p>
This corresponds to a data order where all the consecutive time points of a given voxel are stored together in the file.
This might be useful to optimise throughput for certain applications, for example when the time-course of each voxel is analysed independently.
On the first line, the image space interpretation is given for each entry (suitable for time-series data).
This data order can be interpreted as saying: 
</p>
<ul>
  <li>the first real image dimension (<i>x</i> in this example) is stored second in the file.</li>
  <li>the second real image dimension (<i>y</i> in this example) is stored third in the file.</li>
  <li>the third real image dimension (<i>z</i> in this example) is stored fourth in the file 
  (in reverse order relative to the <a href='overview.html#axes'>standard axes</a>).</li>
  <li>the fourth real image dimension (<i>t</i> in this example) is stored first in the file.</li>
</ul>
<p>
<strong>Note:</strong> all data ordering specifications should be made with reference to 
the <a href='overview.html#axes'>coordinate system convention</a> used by MRtrix.
</p>

<table class=nav>
  <tr>
    <td><a href="cmdline.html"><img src="../left.png"></a></td>
    <td><a href="index.html"><img src="../up.png"></a></td>
    <td><a href="../index.html"><img src="../home.png"></a></td>
    <th><a href='#top'>top</a></th>
    <td><a href="mrview.html"><img src="../right.png"></a></td>
  </tr>
</table>

</body>
</html>


